Scroll to navigation

PERF-SCRIPT(1) perf Manual PERF-SCRIPT(1)

NAME

perf-script - Read perf.data (created by perf record) and display trace output

SYNOPSIS

perf script [<options>]
perf script [<options>] record <script> [<record-options>] <command>
perf script [<options>] report <script> [script-args]
perf script [<options>] <script> <required-script-args> [<record-options>] <command>
perf script [<options>] <top-script> [script-args]

DESCRIPTION

This command reads the input file and displays the trace recorded.

There are several variants of perf script:

´perf script´ to see a detailed trace of the workload that was
recorded.

You can also run a set of pre-canned scripts that aggregate and
summarize the raw trace data in various ways (the list of scripts is
available via ´perf script -l´).  The following variants allow you to
record and run those scripts:

´perf script record <script> <command>´ to record the events required
for ´perf script report´.  <script> is the name displayed in the
output of ´perf script --list´ i.e. the actual script name minus any
language extension.  If <command> is not specified, the events are
recorded using the -a (system-wide) ´perf record´ option.

´perf script report <script> [args]´ to run and display the results
of <script>.  <script> is the name displayed in the output of ´perf
trace --list´ i.e. the actual script name minus any language
extension.  The perf.data output from a previous run of ´perf script
record <script>´ is used and should be present for this command to
succeed.  [args] refers to the (mainly optional) args expected by
the script.

´perf script <script> <required-script-args> <command>´ to both
record the events required for <script> and to run the <script>
using ´live-mode´ i.e. without writing anything to disk.  <script>
is the name displayed in the output of ´perf script --list´ i.e. the
actual script name minus any language extension.  If <command> is
not specified, the events are recorded using the -a (system-wide)
´perf record´ option.  If <script> has any required args, they
should be specified before <command>.  This mode doesn´t allow for
optional script args to be specified; if optional script args are
desired, they can be specified using separate ´perf script record´
and ´perf script report´ commands, with the stdout of the record step
piped to the stdin of the report script, using the ´-o -´ and ´-i -´
options of the corresponding commands.

´perf script <top-script>´ to both record the events required for
<top-script> and to run the <top-script> using ´live-mode´
i.e. without writing anything to disk.  <top-script> is the name
displayed in the output of ´perf script --list´ i.e. the actual
script name minus any language extension; a <top-script> is defined
as any script name ending with the string ´top´.

[<record-options>] can be passed to the record steps of ´perf script
record´ and ´live-mode´ variants; this isn´t possible however for
<top-script> ´live-mode´ or ´perf script report´ variants.

See the ´SEE ALSO´ section for links to language-specific
information on how to write and run your own trace scripts.

OPTIONS

<command>...

Any command you can specify in a shell.

-D, --dump-raw-script=

Display verbose dump of the trace data.

-L, --Latency=

Show latency attributes (irqs/preemption disabled, etc).

-l, --list=

Display a list of available trace scripts.

-s [lang], --script=

Process trace data with the given script ([lang]:script[.ext]). If the string lang is specified in place of a script name, a list of supported languages will be displayed instead.

-g, --gen-script=

Generate perf-script.[ext] starter script for given language, using current perf.data.

-a

Force system-wide collection. Scripts run without a <command> normally use -a by default, while scripts run with a <command> normally don’t - this option allows the latter to be run in system-wide mode.

-i, --input=

Input file name. (default: perf.data unless stdin is a fifo)

-d, --debug-mode

Do various checks like samples ordering and lost events.

-f, --fields

Comma separated list of fields to print. Options are: comm, tid, pid, time, cpu, event, trace, ip, sym, dso, addr, symoff, srcline, period. Field list can be prepended with the type, trace, sw or hw, to indicate to which event type the field list applies. e.g., -f sw:comm,tid,time,ip,sym and -f trace:time,cpu,trace

perf script -f <fields>

is equivalent to:

perf script -f trace:<fields> -f sw:<fields> -f hw:<fields>

i.e., the specified fields apply to all event types if the type string
is not given.

The arguments are processed in the order received. A later usage can
reset a prior request. e.g.:

-f trace: -f comm,tid,time,ip,sym

The first -f suppresses trace events (field list is ""), but then the
second invocation sets the fields to comm,tid,time,ip,sym. In this case a
warning is given to the user:

"Overriding previous field request for all events."

Alternatively, consider the order:

-f comm,tid,time,ip,sym -f trace:

The first -f sets the fields for all events and the second -f
suppresses trace events. The user is given a warning message about
the override, and the result of the above is that only S/W and H/W
events are displayed with the given fields.

For the ´wildcard´ option if a user selected field is invalid for an
event type, a message is displayed to the user that the option is
ignored for that type. For example:

$ perf script -f comm,tid,trace
´trace´ not valid for hardware events. Ignoring.
´trace´ not valid for software events. Ignoring.

Alternatively, if the type is given an invalid field is specified it
is an error. For example:

perf script -v -f sw:comm,tid,trace
´trace´ not valid for software events.

At this point usage is displayed, and perf-script exits.

Finally, a user may not set fields to none for all event types.
i.e., -f "" is not allowed.

-k, --vmlinux=<file>

vmlinux pathname

--kallsyms=<file>

kallsyms pathname

--symfs=<directory>

Look for files with symbols relative to this directory.

-G, --hide-call-graph

When printing symbols do not display call chain.

-C, --cpu

Only report samples for the list of CPUs provided. Multiple CPUs can be provided as a comma-separated list with no space: 0,1. Ranges of CPUs are specified with -: 0-2. Default is to report samples on all CPUs.

-c, --comms=

Only display events for these comms. CSV that understands file://filename entries.

--pid=

Only show events for given process ID (comma separated list).

--tid=

Only show events for given thread ID (comma separated list).

-I, --show-info

Display extended information about the perf.data file. This adds information which may be very large and thus may clutter the display. It currently includes: cpu and numa topology of the host system. It can only be used with the perf script report mode.

--show-kernel-path

Try to resolve the path of [kernel.kallsyms]

--show-task-events Display task related events (e.g. FORK, COMM, EXIT).

--show-mmap-events Display mmap related events (e.g. MMAP, MMAP2).

--header Show perf.data header.

--header-only Show only perf.data header.

--full-source-path

Show the full path for source files for srcline output.

SEE ALSO

perf-record(1), perf-script-perl(1), perf-script-python(1)

05/02/2024 perf